feat(routes): reference MCP App resourceUri from static config and resolve App templates route-relative (#388) - #418

Summary

Fixes #388.

• Static config may reference an MCP App instead of repeating its ui:// literal. Two constrained reference forms join the static route-config grammar (packages/agent-bundle/src/routes/config-extract.ts):
  • appResourceUri('<app>') — a compile-time helper exported from the new light agent-bundle/routes subpath (src/routes/public.ts; 545-byte chunk with no imports, so a route module can import it at run time without pulling the compiler into its generated bundle). The route-graph compiler resolves it after the whole tree is discovered to the target App route's config.resourceUri; accepted references are '<app>' (same server), '<server>/<app>', 'app:<server>/<app>', or a relative module path. An unknown App is the new AB4826 (message lists known App route ids).
  • const string-literal identifiers — a top-level const X = '<literal>' in the route module, or export const X = '<literal>' from a module reached through a relative import inside the project root (.ts/.tsx/.js-style/index resolution, one hop, parsed never executed). This is the issue's APP_RESOURCE_URI from src/constants.ts scenario and stays available at run time (result _meta).
  • Everything else stays AB4806, with messages that now say why the identifier was rejected and a recovery that names both supported forms.
• _meta.ui.resourceUri typing: ToolConfig/ResourceConfig/PromptConfig/AppRouteConfig._meta are RouteMeta (Record<string, unknown> & { ui?: RouteUiMeta }), exported from agent-bundle and agent-bundle/routes.
• config.template is route-file-relative (src/routes/app-template.ts, used by routes/graph.ts and config/normalize.ts), matching how imports resolve. The legacy project-root-relative form is still accepted with no diagnostic while it is the only interpretation naming an existing file. When both interpretations name different existing files, or neither exists, the new AB4827 names both candidate paths and the fix. The IR keeps the authored path (digest stays machine-independent); the normalized model carries the resolved absolute file.
• Docs: docs/diagnostics.md (grammar paragraph, template rule, AB4806 row, new AB4826/AB4827 rows), docs/entry-conventions.md (apps row), docs/framework-mode.md (App route + tool example, _meta row). Changeset .changeset/388-route-config-references.md (minor, new public helper/subpath).
• Codes verified unused in origin/main and open PRs (feat(routes): conventional shared layout module for rendered routes (#312) #396 holds AB4830–AB4832; AB4826/AB4827 taken here).

Not done (scope): the issue's minor note about agent-bundle inspect --routes aborting on diagnostics instead of emitting the partial graph — that requires changing the invalid-inspection result shape/CLI output and is left for a follow-up.

examples/mcp-app needs no change: it uses a config-declared App (config entry/template correctly resolve from the project root, where the config file lives) and reads app.resourceUri from agent-bundle/mcp-apps, so nothing duplicates the literal. Its check (pnpm --filter @agent-bundle-example/mcp-app check) passes.

Evidence

• pnpm typecheck — pass.
• pnpm lint — 0 errors / 0 warnings (1047 files).
• pnpm test:unit — 2755 passed, 2 failed: mcp-probe-service "timed-out probe remained blocked on teardown" and native-claude-contract "fails closed when the candidate plugin…" (5 s timeout). Both are unrelated and environmental: the Claude one hashes the real ~/.claude/plugins tree (324 MB / 1432 files here) and fails identically on a pristine origin/main worktree; the probe one passed on isolated rerun.
• pnpm test:route-unit — 36 passed, 1 failed (lifecycle-replay 5 s timeout) → passed on isolated rerun.
• pnpm test:projection — 66 passed.
• pnpm build && pnpm test:integration:run — 948 passed, 0 failed.
• New build-level test (generated-route-server.test.ts, "Static route config grammar forbids identifier references, so an MCP App's resourceUri must be duplicated as a literal in every tool's _meta.ui.resourceUri; config.template resolves from the project root #388") passes: an App route with an imported-const resourceUri and a route-relative template, a tool using appResourceUri('dashboard'), and a resource importing the same const; the built server lists _meta.ui.resourceUri resolved for both and the compiled App HTML comes from the route-relative template.

Test plan

• tests/route-config-extract.test.ts: same-module const; imported const (.js-style and index specifiers); rejections for package specifier, missing module, outside-project module, missing export, non-literal export, type-only import, default import (all AB4806 naming both forms); appResourceUri() placeholder recording (paths + positions) and resolution by bare name, qualified id, app: id, relative path with/without extension; unknown App → AB4826 (+ bare-form hint outside MCP routes); helper not imported / wrong specifier / non-string / arity / dynamic argument → AB4806.
• tests/route-graph.test.ts: cross-route resolution (tool, resource, prompt, cross-server tool) to the App URI incl. digest sensitivity; AB4826 + AB4806 side by side; template route-relative / legacy root-relative (no diagnostic) / ambiguous (AB4827 names both) / missing (AB4827) and digest stability; normalized mcpApps[].template for route-relative and legacy, validate/inspect invalid on ambiguity.
• tests/generated-route-server.test.ts: end-to-end build + stdio listing as above.
• pnpm --filter @agent-bundle-example/mcp-app check passes.